package cz.muni.fi.pa165.musiclibrary.api.service;

import cz.muni.fi.pa165.musiclibrary.api.service.dto.IArtistDTO;
import java.util.List;

/**
* Service interface for working with artists.
* 
* @author Martin Szabo
* 2012-11-02T22:58:11+0100
*/
public interface IArtistService {
/**
     * Add new entry of given artist to database.
     * Artist could not have assigned identifier.
     *  
     * @param artist Artist (DTO) to be inserted
     * @throws TBD
     * <ul>
     *  <li>parameter is {@code null},</li>
     *  <li>artist identifier is <strong>not</strong> {@code null}.
     * </ul>
     */
    void create(final IArtistDTO artist);
    
    /**
     * Edit existing entries selected by parameter which has to have assigned
     * identifier.
     * 
     * @param artist Artist(DTO) to be updated
     * @throws IllegalArgumentException If:
     * <ul>
     *  <li>parameter is {@code null},</li>
     *  <li>artist identifier is {@code null}.
     * </ul>
     */
    void update(final IArtistDTO artist);
    
    /**
     * Remove entry by given parameter which has to have assigned identifier.
     * 
     * @param artist to be removed
     * @throws IllegalArgumentException If:
     * <ul>
     *  <li>parameter is {@code null},</li>
     *  <li>artist identifier is {@code null}.
     * </ul>
     */
    void delete(final IArtistDTO artist);
    
    /**
     * Find and return DTO object by ({@link #getIdArtist()})
     * 
     * @param idArtist defines which entry should be found
     * @return adequate entity or {@code null} if there is none for given identifier.
     */   
    IArtistDTO getById(final Long idArtist);
    /**
     * Find and return collection of DTO objects by ({@link #getName()})
     * 
     * @param name defines which entry should be found
     * @return adequate entity or empty collection if there is none for given identifier.
     */   
    List<IArtistDTO> getByName(final String name);
    
    /**
     * Return collection of all artists DTO stored in database.
     * Never returns {@code null}, if there are no 
     *  artists, returns empty list.
     * 
     * @return collection of all artists
     */
    List<IArtistDTO> getAll();
}
